--- id: Banking - Collections-spec handle: Collections title: "Ficha técnica" description: "Collection" custom_edit_url: null --- ## Escopos necessários O token para consumir a API de Cobranças deve ser gerado usando o Authorization Code. **O escopo `openid`é obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.** É necessário incluir o seguinte escopo: | Escopo | Descrição | | :-------------------------------------------- | :-------------------------------------- | | brn:btg:empresas:banking:collections | Permite a consulta e gestão de cobrança | | brn:btg:empresas:banking:collections.readonly | Permite apenas consulta de cobranças | ## Recursos Disponíveis Com esta API é possível emitir cobranças em formato de boleto tradicional, boleto híbrido, ou PIX. Além disso, é possível configurar na requisição uma série de parametros como juros, multa datas de vencimento e limite de pagamento e mais. Verifique os payloads de criação em Criar Cobrança. ### Boleto tradicional A criação de um boleto tradicional é definido pela propriedade `type` e ocorre quando esta assume o valor `BANKSLIP`. ```json { "type":"BANKSLIP", "amount":10, //Restante do boleto... } ``` ### Boleto híbrido A criação de um boleto híbrido é definido pela propriedade `type` e ocorre quando esta assume o valor `BANKSLIP_QRCODE`. O boleto híbrido possui toda a estrutura de um boleto tradicional, porém é acompanhado de um QR Code para pagamento via PIX Esta modalidade permite a utilização da jornada 4 do PIX Automático, caso o objeto. ```json { "type":"BANKSLIP_QRCODE", "amount":10, //Restante do boleto híbrido... } ``` ### PIX Cobrança QR Code com data de vencimento A criação de um PIX Cobrança com data de vencimento é definido pela propriedade `type` e ocorre quando esta assume o valor `DUE_DATE_QRCODE` ```json { "type":"DUE_DATE_QRCODE", "amount":10, //Restante do PIX Cobrança... } ``` ## Especificidades ### Utilização da jornada 4 do PIX Automático > ❗️ Importante > > A criação da autorização e, consequentemente, a inicio da jornada 4 ocorrerá **SOMENTE SE** o pagamento do boleto for realizado por meio do QR Code. Outros métodos de pagamento do boleto não iniciaram a jornada de PIX Automático. A jornada 4 do PIX Automático pode ser utilizada somente na emissão de boletos híbridos. Para ativar a jornada, é necessário que seja criado um boleto híbrido e adicionamente seja passado um objeto `automaticPixDetails` conforme exemplo: ```json { "type": "BANKSLIP_QRCODE", "automaticPixDetails": { "period": "ANNUALLY", "retryPolicy": "ACCEPT_3R_7D", "contract": "54872120205AASS12", "initialDate": "2025-04-18" } //Restante do payload do boleto... } ``` ### Juros pencentuais O campo de juros na opção percentual é cobrado diariamente após o vencimento da cobrança, mas o valor percentual deve ser configurado **em relação ao quanto se deseja cobrar mensalmente**. Por exemplo, se você deseja cobrar 0.03% de juros ao dia, deve-se realizar o post com o valor pencentual de 1%. ```json { //restante do payload do boleto "interests": { "arrears": { "type": "PERCENTAGE", "value": 1 } }, //restante do payload do boleto } ``` Vale ressaltar que o juros é cobrado por dias corridos, então seriam acrescidos 0,03% de juros mesmo em fins de semana e feriados. ## Status da cobrança Uma cobrança pode ter diversos status: | Status | Descrição | | :------------ | :-------------------------------- | | CREATED | Cobrança emitida | | PAID | Cobrança pago | | CANCELED | Cobrança cancelada | | EXPIRED | Cobrança vencida | | PROCESSING | Cobrança em processamento | | FAILED | Falha na emissão da cobrança | | UPDATED | Cobrança atualizado | | UPDATING | Cobrança em atualização | | CANCEL_FAILED | Falha no cancelamento da cobrança | | RETURNED | Cobrança estornada | | CANCELING | Cobrança em cancelamento | ## Eventos de webhook Os payloads disponíveis abaixo representam o conteúdo do campo `data`. | Evento | Descrição | | :--------------------- | :------------------ | | `collections.created` | Cobrança criada. | | `collections.paid` | Cobrança paga. | | `collections.expired` | Cobrança expirada. | | `colections.cancelled` | Cobrança cancelada. | ### collections.created ```json { "amount": 4620, "origin": "APP", "dueDate": "2025-10-07", "overDueDate": "2026-02-04", "type": "BANKSLIP", "payer": { "address": { "number": "11111", "zipCode": "111111111", "city": "VOLTA REDONDA", "street": "RUA", "state": "RJ", "neighborhood": "JARDIM AMÁLIA" }, "taxId": "21342341243234", "name": "NOME", "personType": "J" }, "floatingInDays": 1, "payee": { "branchCode": "50", "bankCode": "208", "number": "12342134234", "taxId": "2123421400103", "name": "NOME", "personType": "J" }, "installmentNumber": 1, "createdAt": "2025-08-08T18:35:25.000Z", "totalInstallments": 1, "timelineException": false, "discounts": [ { "type": "NOT_APPLICABLE", "value": 0 } ], "interest": { "type": "NOT_APPLICABLE", "value": 0 }, "fine": { "type": "NOT_APPLICABLE", "value": 0 }, "automaticBadCreditException": false, "anticipation": { "isAnticipated": false }, "correlationId": "new-bill", "detail": { "documentNumber": "5269/3", "externalId": "5edb5555-54c1-4ab7-960e-f54055555d212", "ourNumber": "13752155718125475", "barCode": "555555543213400000500155755555505224880", "digitableLine": "20812555555555806112270000462000" }, "collectionId": "555555-7dcd-4ab9-bdd1-555555b4", "updatedAt": "2025-08-08T18:35:25.000Z", "status": "CREATED" } ``` ### collections.paid ```json { "amount": 9200, "origin": "WEB", "dueDate": "2025-08-12", "overDueDate": "2025-12-10", "type": "BANKSLIP_QRCODE", "payer": { "address": { "number": "11111", "zipCode": "521341240", "city": "Recife", "street": "RUA", "state": "PE", "neighborhood": "Tamarineira", "complement": "até 3514/3515" }, "taxId": "01324124321464", "name": "NOME", "personType": "J" }, "payee": { "branchCode": "50", "bankCode": "208", "number": "123421424", "taxId": "1234214214", "name": "NOME", "personType": "J" }, "createdAt": "2025-06-13T21:36:06.000Z", "timelineException": false, "discounts": [ { "type": "NOT_APPLICABLE", "value": 0 } ], "amountPaid": 9200, "interest": { "type": "PERCENTAGE_PER_MONTH", "value": 8, "startDate": "2025-08-13" }, "fine": { "type": "NOT_APPLICABLE", "value": 0 }, "automaticBadCreditException": false, "anticipation": { "anticipationDate": "2025-06-16", "isAnticipated": true }, "settledAt": "2025-08-08", "paidAt": "2025-08-08", "paymentMethod": "QRCODE", "correlationId": "new-bill", "detail": { "documentNumber": "28045", "externalId": "644444ce2-4444-40e4-8e4f-144444444", "ourNumber": "84306546310566684", "barCode": "2012342142148405378560", "digitableLine": "201234124124124124920000", "emv": "00020101021226960014br.gov.bcb.pix2574api.developer.btgpactual.com/v1/p/v2/cobv/4444447a95fc5442ca144444830664479d524444449865802BR5925DMH - TESTE6009SAO PAULO61080453813362070503***630426B7" }, "collectionId": "444444e81-6cef-4bf7-44444-4240309f67d5", "updatedAt": "2025-08-08T18:34:32.000Z", "status": "PAID" } ``` ### collections.expired ```json { "collectionId": "be9ed6e9-4444-4f8a-8c8a-ef4441ad44b6", "createdAt": "2025-03-08T06:20:49.341Z", "amount": 487.25, "batchId": "444444ce8-1611-4284-a541-7af4444444a", "deliveryMediums": [], "type": "BANKSLIP", "payee": { "name": "NAME", "bankCode": "208", "branchCode": "1", "number": "004444445", "personType": "J", "taxId": "52664444444435" }, "updatedAt": "2025-03-08T06:20:53.000Z", "origin": "CNAB", "payer": { "taxId": "4444446153", "name": "NAME", "personType": "F", "address": { "city": "S.CAETANO SUL", "number": "83", "state": "SP", "street": "RUA SAMUEL KLEIN", "zipCode": "09510125", "neighborhood": "CENTRO" } }, "status": "EXPIRED", "correlationId": "54444444140049350804", "badCredit": {}, "anticipation": { "isAnticipated": false }, "detail": { "externalId": "e44444-62ab-46c8-8b5b-4444443fe61", "barCode": "208941144444410000058465444444090", "digitableLine": "208444444444071090441135044444425", "ourNumber": "00000444444", "documentNumber": "000000000000000" }, "interest": { "startDate": "2025-07-08", "type": "PERCENTAGE_PER_MONTH", "value": 9.96 }, "fine": { "startDate": "2025-07-08", "type": "PERCENTAGE", "value": 4 }, "discounts": [ { "limitDate": "2025-07-02", "type": "PERCENTAGE", "value": 1.5 } ], "overDueDate": "2025-08-06", "dueDate": "2025-07-07", "installmentNumber": 1, "totalInstallments": 1, "automaticBadCreditException": false, "timelineException": false } ``` ### collections.cancelled ```json { "amount": 2.97, "origin": "WEB", "dueDate": "2025-12-13", "description": "DESCRIÇÃO", "overDueDate": "2026-12-13", "type": "BANKSLIP_QRCODE", "payer": { "taxId": "17584193773", "name": "Carlos Caliman", "personType": "F" }, "floatingInDays": 1, "payee": { "branchCode": "50", "bankCode": "208", "number": "0107444444", "taxId": "474444444108", "name": "NOME", "personType": "J" }, "installmentNumber": 1, "createdAt": "2025-07-28T21:05:50.000Z", "totalInstallments": 1, "timelineException": false, "discounts": [ { "type": "NOT_APPLICABLE", "value": 0 } ], "canceledAt": "2025-08-08", "interest": { "type": "FIXED_VALUE_PER_DAY", "value": 2, "startDate": "2025-12-14" }, "fine": { "type": "PERCENTAGE", "value": 1, "startDate": "2025-12-14" }, "automaticBadCreditException": false, "anticipation": { "isAnticipated": false }, "correlationId": "new-bill", "detail": { "documentNumber": "teste", "externalId": "3444470-a44e-48bc-8b19-6aa244444e32", "ourNumber": "74198196346750084", "barCode": "2089444444444440001050050014444444410773460", "digitableLine": "20890050091963444444444604112940000000105", "emv": "00020101021226980014br.gov.bcb.pix2576api-h.developer.btgpactual.com/pc/p/v2/cobv/5b3969415dca40758c8bad8ae849dd64520444444445802BR5925TESTEsao paulo62070503***63044F03" }, "collectionId": "4444bf8b-f0e7-4444-9cd7-c6ef444f2af5", "updatedAt": "2025-08-08T19:15:06.000Z", "status": "CANCELED" } ```